fix: harden Paykit request handling - #684

Greptile Summary

This PR hardens incoming Paykit contact-payment handling by isolating malformed receiver markers and validating request amounts against the balance before entering the send flow.

• Allows valid contacts’ private endpoints to publish when another contact has a malformed receiver marker.
• Uses the incoming Paykit request amount for Lightning and on-chain preflight balance checks.
• Adds a changelog entry describing the corrected behavior.

Confidence Score: 5/5

The PR appears safe to merge, with the changed preflight checks aligned to the amount ultimately paid and malformed markers safely isolated from valid contacts.

Private Paykit endpoints are intentionally amountless, the incoming request amount is injected into payment execution and checked again during confirmation, and valid receiver paths continue through publication while malformed paths remain rejected and logged.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Incoming Paykit request] --> B[Resolve private amountless endpoint]
  B --> C[Decode Lightning, on-chain, or unified target]
  C --> D[Read amount from incoming request]
  D --> E{Preferred route has sufficient balance?}
  E -->|Yes| F[Open shared send flow]
  E -->|No, unified request| G{On-chain balance sufficient?}
  G -->|Yes| F
  G -->|No| H[Show insufficient balance message]
  E -->|No, single route| H
  F --> I[Inject request amount]
  I --> J[Confirm exact request amount]
  J --> K[Pay]

_{Reviews (1): Last reviewed commit: "fix: harden Paykit contact payments" | Re-trigger Greptile}

Retested after 97033fe.

Enable — still fails. ❌

Toggle Enable payments with contacts → Private Paykit is not available, toggle does not stay on. Same staging contact as the Android QA (pubky1jy146y751hkgqk9p69ds5cqf461aj5x7c8ptbca5rw6m9asotso). Recording + logs attached.

This is not the malformed-marker isolation path. enable() still calls preparePrivateEndpoints(..., requireImmediate: true) before setting publishingEnabledKey. canPublishPrivateEndpoints requires that flag already true, so any saved contact fail-closes as privateUnavailable.

Same surface on Android #1172 (toast there is Unknown error).

Steps:

1. Paykit UI on. Profile exists. Staging pubky above saved as a contact (need not be live).
2. Payments with contacts off.
3. Enable payments with contacts.
4. Toast is Private Paykit is not available; toggle stays off.

bitkit_logs_2026-08-27_08-28-24.zip

Over-balance — copy is fixed, toast loops. ❌

Pay on a request larger than the wallet now shows the right message (Insufficient Savings, e.g. ₿ 26,717 more needed) instead of coin selection. On Android that toast fires once. On iOS it keeps coming back. Tapping Pay again then shows The payment request is already being processed. Recording attached.

validateOnchainBalance toasts and returns; presentNextIncomingPaykitPaymentRequest then deferPresentation (2s × 14). Each retry runs handleScannedData again and toasts again. Android’s equivalent is clearActiveContactPaymentContext(retryIncomingRequest = false) after the insufficient toast — no retry.

Steps:

1. Two live wallets, payments with contacts on. Payer under the request amount (split savings + spending is fine).
2. Other wallet requests more than that total.
3. On iOS, tap Pay on the incoming request / See All row.
4. Insufficient Savings toast repeats. A second Pay can show already being processed.

bitkit_logs_2026-08-27_09-15-42-overbalance.zip

Fixed both retest findings in 5ba7ee7. Private publication is now enabled before immediate endpoint preparation, with rollback still handled by the existing failure path. An unaffordable request is marked surfaced after the single balance toast, so it remains in the bell/history queue without the 2-second automatic retry loop or already-processing follow-up. The focused iOS suites pass 56/56 tests.

Retested 112fb70.

Over-balance: fixed. One insufficient-capacity toast, no retry loop. ✅

Enable: still broken. Five toggles failed with privateUnavailable ❌
(09:41:49, 09:41:57, 09:46:04, 09:46:17, 09:46:25). Setting
publishingEnabledKey first did not help.

Logs never reach inspect/prepare/queue/deliver. 09:46:04 is
pubky_secret_key loaded → enable ERROR in 2ms, so this is still
canPublishPrivateEndpoints == false + requireImmediate + a saved
contact, then restore() rolls the toggle off.

Also still had pubky8u997gg after deleting pubky1jy146y, so this
is not specific to that staging contact.

Need the failing canPublish clause logged, and enable should not
fail-close when publication never actually ran.

bitkit_logs_2026-09-01_09-46-59.zip

Fixed the remaining enable failure in 2d90e0e. Private endpoint preparation during enable is now best effort, so temporary wallet, node, app, or Pubky unreadiness defers publication instead of returning privateUnavailable and rolling the toggle back. Real errors after publication starts still fail and restore the previous state. The readiness check now logs the exact unavailable condition. ContactPaymentsServiceTests and PrivatePaykitServiceTests pass 24 of 24. @piotr-iohk please retest the Enable case, and @ovitrif please re-review the updated head.

Retested latest revision (2d90e0e), iPhone 17 sim.

Enable still fail-closes. Toggle → Failed to update contact payments: privateUnavailable (GeneralSettingsView.updateContactPayments line 180) → “Private Paykit is not available.”

2d90e0e is on this build — startup logged Deferring private Paykit endpoint publication during prepare: private publication is disabled (flag off, 0 contacts). On the enable attempt itself there was no second defer: flag was set, canPublish passed, then it still threw. Sequence: loaded 1 contact (pubkypwuhkhj…), then the error ~11s later. No Failed to inspect/prepare/sync WARN around the fail.

Hypothesis: requireImmediatePublication: false on enable is bypassed by the unguarded return error after receiverPathSelection in syncLocalEndpointPublicationLocked. Other failures on that path are supposed to defer.

Android enable stays on after the matching defer change.

Logs:
bitkit_logs_2026-09-01_15-09-55.zip

You were right about the remaining fail-closed path. The receiverPathSelection catch returned immediately before the deferred-publication policy was applied. Signed commit ab3308b8 now records/logs that per-contact error, continues reconciliation, and returns it only for immediate publication.

The regression test covers this exact selection failure, and the focused private/contact/request suites pass 74/74. I also installed this exact head over the saved-contact QA state, enabled Paykit UI, and verified the toggle stayed enabled past 15 seconds with the success toast and no privateUnavailable rollback. Please retest ab3308b8 after the fresh checks finish.

Retested ab3308b on latest local head. Enable/disable with the same staging contact (pubky1jy146y751hkgqk9p69ds5cqf461aj5x7c8ptbca5rw6m9asotso) still showed Private Paykit is not available. and the toggle did not stay off. Android does not toast and the switch turns off.

Same privateUnavailable on both platforms (cleanup/delivery to that contact fails). Android defers private cleanup and keeps the toggle off. iOS was still throwing from disable(), toasting, and restoring the previous on state.

I brought the Android disable logic over in 9104ff4: failed private cleanup now marks cleanup pending and succeeds the toggle. After that change the toast is gone and the switch stays off. Public cleanup still fail-closes.

@ben-kaufman @ovitrif please review if this makes sense.

Before (ab3308b)

ios on the left:

After (9104ff4)